/*
 * Component.java
 *
 * Created on July 30, 2006, 11:41 PM
 *
 * (C) R. Alexander Milowski alex@milowski.com
 */

package org.infoset.component;

import java.net.URI;
import java.util.Collection;
import java.util.logging.Logger;
import org.infoset.xml.Document;
import org.infoset.xml.DocumentLoader;
import org.infoset.xml.Infoset;
import org.infoset.xml.ItemDestination;
import org.infoset.xml.Name;
import org.infoset.xml.NamespaceScope;
import org.infoset.xml.XMLException;

/**
 * During the lifetime of a component, the following happens:
 * 1. The init() method is called with the component context.  This
 *    usually happens with the pipeline is initialized with the
 *    context of the environment of the pipline.
 * 2. bindResource() is called for any staticly determined document
 *    inputs (e.g. here documents or documents loaded by URI).
 * 3. bindOutputPort() is called to establish the output ports for
 *    the component.
 * 4. onStart() is called when the pipeline processing is started.
 * 5. Some some sequence of getInputPort() or onDocumentInput() methods
 *    are called depending on the component definition and pipeline.
 * 6. onEnd() is called at the end of pipeline processing.
 * @author R. Alexander Milowski
 */
public interface Component {
   
   interface Context {
      
      Logger getLog();

      /**
       * Returns the in-scope namespace mappings
       */
      NamespaceScope getNamespaceScope();
      
      /**
       * Gets a parameter value for the parameter name.
       */
      Object getParameter(Name name);
      /**
       * Returns all the available parameter names.
       */
      Collection<Name> getParameterNames();
      /**
       * Gets the base URI of the pipeline
       */
      URI getBaseURI();
      
      /**
       * Returns the current document loader for the component
       */
      DocumentLoader getDocumentLoader();
      
      /**
       * Returns the current infoset for the component
       */
      Infoset getInfoset();
   }

   /**
    * Initializes the component with a context
    * @param context The pipeline context for this component
    * @throws XMLException Thrown when the component cannot initialize itself.
    */
   void init(Context context)
      throws XMLException;

   /**
    * Binds a statically know input port to an item source (document).
    * @param port The name of the input port that is being statically bound.
    * @param source The item source containing the document.
    * @throws XMLException Thrown when the port name is invalid or there were other issues with using the resource.
    */
   void bindResource(Name port,Document document)
      throws XMLException;
   
   /**
    * Binds a statically know input port to an item source (document).
    * @param port The name of the input port that is being statically bound.
    * @param source The item source containing the document.
    * @throws XMLException Thrown when the port name is invalid or there were other issues with using the resource.
    */
   void bindResource(Name port,URI location)
      throws XMLException;
   
   /**
    * Binds an output source to a destination.
    * @param port The name of the output port that is being bound.
    * @param output The item destination for the output.
    * @throws XMLException Thrown when the port name is invalid or there were other issues with establishing the output.
    */
   void bindOutputPort(Name port,ItemDestination output)
      throws XMLException;
   
   /**
    * Indicates that pipeline processing is starting.
    * @throws XMLException Thrown when the component cannot be started.
    */
   void onStart()
      throws XMLException;
   
   /**
    * Called to get an item destination for the input port.
    * @param port The name of the input port.
    * @throws XMLException Thrown when the port name is invalid or there were other issues with establishing the input.
    */
   ItemDestination getInputPort(Name port)
      throws XMLException;

   /**
    * A callback for receiving a document on an input port.
    * @param port The name of the input port.
    * @param doc The document being received.
    * @throws XMLException Thrown when the port name is invalid or there were other issues with establishing the input.
    */
   void onDocumentInput(Name port,Document doc)
      throws XMLException;
   
   /**
    * Indicates that pipeline processing has ended.
    * @throws XMLException Thrown when the component cannot be stopped.
    */
   void onEnd()
      throws XMLException;
   
}
